Subscription Management API

The Subscription Management API provides administrators and resellers with the ability to manage user subscriptions, including removing subscriptions, reverting changes, and adjusting subscription durations.

Overview

This API provides three main operations:

• Remove User Subscription
• Revert Last Subscription Change
• Revert to Specific Days

Authorization

important

These mutations require authentication and proper authorization. Only administrators and resellers can perform these operations. Resellers can only manage subscriptions for their own users.

API Reference

Remove User Subscription

Completely removes a user's subscription from the system.

mutation RemoveSubscription($username: String!) {
  removeUserSubscription(username: $username) {
    id
    expiresAt
    group {
      id
      name
    }
    multiLoginCount
    dailyBandwidth
    downloadUpload
    isTrialPeriod
    duration
    price
    gateway
  }
}

Variables

{
  "username": "test@example.com"
}

Response

{
  "data": {
    "removeUserSubscription": {
      "id": 123,
      "expiresAt": "2024-12-31T23:59:59",
      "group": {
        "id": 1,
        "name": "Premium"
      },
      "multiLoginCount": 5,
      "dailyBandwidth": 1000000000,
      "downloadUpload": 100000000,
      "isTrialPeriod": false,
      "duration": 30,
      "price": 9.99,
      "gateway": "STRIPE"
    }
  }
}

Revert Last Subscription Change

Reverts to previous subscription state while maintaining the remaining time.

mutation RevertSubscription($username: String!) {
  revertLastSubscriptionChange(username: $username) {
    id
    expiresAt
    group {
      id
      name
    }
    multiLoginCount
    dailyBandwidth
    downloadUpload
    isTrialPeriod
    duration
    price
    gateway
  }
}

Variables

{
  "username": "test@example.com"
}

Revert to Specific Days

Reverts a subscription to a specific number of remaining days.

mutation RevertToSpecificDays($username: String!, $days: Int!) {
  revertSubscriptionToDays(username: $username, remainingDays: $days) {
    id
    expiresAt
    group {
      id
      name
    }
    multiLoginCount
    dailyBandwidth
    downloadUpload
    isTrialPeriod
    duration
    price
    gateway
  }
}

Variables

{
  "username": "test@example.com",
  "days": 6
}

Implementation Guide

Admin Portal Implementation

1. Remove a subscription:

const response = await client.mutate({
  mutation: gql`
    mutation RemoveSubscription($username: String!) {
      removeUserSubscription(username: $username) {
        id
        expiresAt
        group {
          id
          name
        }
      }
    }
  `,
  variables: { username },
});

2. Revert last change:

const response = await client.mutate({
  mutation: gql`
    mutation RevertSubscription($username: String!) {
      revertLastSubscriptionChange(username: $username) {
        id
        expiresAt
        group {
          id
          name
        }
      }
    }
  `,
  variables: { username },
});

3. Revert to specific days:

const response = await client.mutate({
  mutation: gql`
    mutation RevertDays($username: String!, $days: Int!) {
      revertSubscriptionToDays(username: $username, remainingDays: $days) {
        id
        expiresAt
        group {
          id
          name
        }
      }
    }
  `,
  variables: {
    username,
    days: 6,
  },
});

Best Practices

1. Authorization

   • Always verify admin/reseller permissions
   • Validate reseller ownership of users
   • Use proper authentication headers

2. Data Validation

   • Validate usernames before operations
   • Ensure positive day values
   • Verify subscription existence

3. Error Handling

   • Handle all possible error states
   • Provide clear error messages
   • Implement proper logging

Error Handling

Common errors and their meanings:

Error Message	Description	Solution
Unauthorized	User is not admin/reseller	Verify permissions
User not found	Username doesn't exist	Check username
No subscription found	User has no active subscription	Verify subscription status
Invalid days	Negative days provided	Use positive number
Not your user	Reseller trying to manage another's user	Check user ownership

Security Considerations

• Only admins and resellers can access these mutations
• Resellers can only manage their own users
• All operations are transactional
• Actions are logged and tracked
• Webhook events are generated for all changes

Webhook Events

The following webhook events are triggered:

• SUBSCRIPTION_REMOVED: When a subscription is removed
• SUBSCRIPTION_REVERTED: When a subscription is reverted to a previous state